home *** CD-ROM | disk | FTP | other *** search
/ Nothing but GIFs AGA / Nothing But GIFs.iso / immogrif.lha / imagemagick / mogrify.txt < prev    next >
Text File  |  1995-07-17  |  24KB  |  602 lines
  1. NAME
  2.        mogrify - transform an image or sequence of images
  3.  
  4. SYNOPSIS
  5.        mogrify [ options ...] file [ [ options ...] file ...]
  6.  
  7. DESCRIPTION
  8.        mogrify transforms an image or a sequence of images.
  9.        These transforms include image scaling, image rotation,
  10.        color reduction, and others.  The transmogrified image
  11.        overwrites the original image.
  12.  
  13. EXAMPLES
  14.        To convert all the TIFF files in a particular directory to
  15.        JPEG, use:
  16.  
  17.            mogrify -format jpeg *.tiff
  18.  
  19.        To scale an image of a cockatoo to exactly 640 pixels in
  20.        width and 480 pixels in height, use:
  21.  
  22.            mogrify -geometry 640x480! cockatoo.miff
  23.  
  24.        To create a single colormap for a sequence of bird images,
  25.        use:
  26.  
  27.            mogrify -colors 256 scenes/birds.*
  28.  
  29. OPTIONS
  30.        -annotate string
  31.             annotate an image with text.
  32.  
  33.             Use this option to annotate an image with text.
  34.             Optionally you can include the image filename, type,
  35.             width, height, or scene number by embedding special
  36.             format characters.  Embed %f for filename, %m for
  37.             magick, %w for width, %h for height, %s for scene
  38.             number, or \n for newline.  For example,
  39.  
  40.                  -annotate "%m:%f %wx%h"
  41.  
  42.             annotates the image with MIFF:bird.miff 512x480 for
  43.             an image titled bird.miff and whose width is 512 and
  44.             height is 480.
  45.  
  46.             If the first character of string is @, the text is
  47.             read from a file titled by the remaining characters
  48.             in the string.
  49.  
  50.             You can set the text position, font, and font color
  51.             with -geometry, -font, and -pen respectively.
  52.             Options are processed in command line order so be
  53.             sure to use -geometry, -font, or -pen before the
  54.             -annotate option.
  55.  
  56. ImageMagick                 1 May 1994                          1
  57.  
  58.        -blur factor
  59.             blurs an image.  Specify factor as the percent
  60.             enhancement (0.0 - 99.9%).
  61.  
  62.        -border <width>x<height>
  63.             surround the image with a border or color.  See X(1)
  64.             for details about the geometry specification.
  65.  
  66.             The color of the border is obtained from the X server
  67.             and is defined as bordercolor (class borderColor).
  68.             See X(1) for details.
  69.  
  70.        -colors value
  71.             preferred number of colors in the image.
  72.  
  73.             The actual number of colors in the image may be less
  74.             than your request, but never more.  Note, this is a
  75.             color reduction option.  Images with less unique
  76.             colors than specified with this option will remain
  77.             unchanged.  Refer to quantize(9) for more details.
  78.  
  79.             If more than one image is specified on the command
  80.             line, a single colormap is created and saved with
  81.             each image.
  82.  
  83.             Note, options -colormap, -dither, -colorspace, and
  84.             -treedepth affect the color reduction algorithm.
  85.  
  86.        -colorspace value
  87.             the type of colorspace: GRAY, OHTA, RGB, XYZ, YCbCr,
  88.             YIQ, YPbPr, or YUV.
  89.  
  90.             Color reduction, by default, takes place in the RGB
  91.             color space.  Empirical evidence suggests that
  92.             distances in color spaces such as YUV or YIQ
  93.             correspond to perceptual color differences more
  94.             closely than do distances in RGB space.  These color
  95.             spaces may give better results when color reducing an
  96.             image.  Refer to quantize(9) for more details.
  97.  
  98.             The -colors or -monochrome option is required for
  99.             this option to take effect.
  100.  
  101.        -comment string
  102.             annotate an image with a comment.
  103.  
  104.             By default, each image is commented with its file
  105.             name.  Use this option to assign a specific comment
  106.             to the image.  Optionally you can include the image
  107.             filename, type, width, height, or scene number by
  108.             embedding special format characters.  Embed %f for
  109.             filename, %m for magick, %w for width, %h for height,
  110.             %s for scene number, or \n for newline.  For example,
  111.  
  112. ImageMagick                 1 May 1994                          2
  113.  
  114.                  -comment "%m:%f %wx%h"
  115.  
  116.             produces an image comment of MIFF:bird.miff 512x480
  117.             for an image titled bird.miff and whose width is 512
  118.             and height is 480.
  119.  
  120.             If the first character of string is @, the image
  121.             comment is read from a file titled by the remaining
  122.             characters in the string.
  123.  
  124.        -compress type
  125.             the type of image compression: QEncoded or
  126.             RunlengthEncoded.
  127.  
  128.             Specify +compress to store the binary image in an
  129.             uncompressed format.  The default is the compression
  130.             type of the specified image file.
  131.  
  132.        -contrast
  133.             enhance or reduce the image contrast.
  134.  
  135.             This option enhances the intensity differences
  136.             between the lighter and darker elements of the image.
  137.             Use -contrast to enhance the image or +contrast to
  138.             reduce the image contrast.
  139.  
  140.        -crop <width>{%}x<height>{%}{+-}<x offset>{+-}<y offset>
  141.             preferred size and location of the cropped image.
  142.             See X(1) for details about the geometry
  143.             specification.
  144.  
  145.             To specify a percentage width or height instead,
  146.             append %.  For example to crop the image by ten
  147.             percent on all sides of the image, use -crop 10%.
  148.  
  149.             Use cropping to apply image processing options, or
  150.             transmogrify, only a particular area of an image.
  151.             Use -crop 0x0 to remove edges that are the background
  152.             color.
  153.  
  154.        -density <width>x<height>
  155.             vertical and horizontal resolution in pixels of the
  156.             image.
  157.  
  158.             This option specifies an image density when decoding
  159.             a Postscript or Portable Document page.  The default
  160.             is 72 pixels per inch in the horizontal and vertical
  161.             direction.
  162.  
  163.        -despeckle
  164.             reduce the speckles within an image.
  165.  
  166.        -display host:display[.screen]
  167.             specifies the X server to contact; see X(1).
  168.  
  169. ImageMagick                 1 May 1994                          3
  170.  
  171.        -dither
  172.             apply Floyd/Steinberg error diffusion to the image.
  173.  
  174.             The basic strategy of dithering is to trade intensity
  175.             resolution for spatial resolution by averaging the
  176.             intensities of several neighboring pixels.  Images
  177.             which suffer from severe contouring when reducing
  178.             colors can be improved with this option.
  179.  
  180.             The -colors or -monochrome option is required for
  181.             this option to take effect.
  182.  
  183.        -edge
  184.             detect edges within an image.
  185.  
  186.        -emboss
  187.             emboss the image.
  188.  
  189.        -enhance
  190.             apply a digital filter to enhance a noisy image.
  191.  
  192.        -equalize
  193.             perform histogram equalization to the image.
  194.  
  195.        -flip
  196.             create a "mirror image" by reflecting the image
  197.             scanlines in the vertical direction.
  198.  
  199.        -flop
  200.             create a "mirror image" by reflecting the image
  201.             scanlines in the horizontal direction.
  202.  
  203.        -format type
  204.             the image format type.
  205.  
  206.             This option will convert any image to the image
  207.             format you specify.  See convert(1) for a list of
  208.             image format types supported by ImageMagick.
  209.  
  210.             By default the file is written to its original name.
  211.             However, if the filename extension matches a
  212.             supported format, the extension is replaced with the
  213.             image format type specified with -format.  For
  214.             example, if you specify tiff as the format type and
  215.             the input image filename is image.gif, the output
  216.             image filename becomes image.tiff.
  217.  
  218.        -font name
  219.             This option specifies the font to be used  for
  220.             displaying normal text.  The default is fixed.
  221.  
  222.        -frame <width>x<height>+<outer bevel width>+<inner bevel
  223.             width>
  224.             surround the image with an an ornamental border.  See
  225.  
  226. ImageMagick                 1 May 1994                          4
  227.  
  228.             X(1) for details about the geometry specification.
  229.  
  230.             The color of the border is specified with the
  231.             -mattecolor command line option.
  232.  
  233.        -gamma value
  234.             level of gamma correction.
  235.  
  236.             The same color image displayed on two different
  237.             workstations may look different due to differences in
  238.             the display monitor.  Use gamma correction to adjust
  239.             for this color difference.  Reasonable values extend
  240.             from 0.8 to 2.3.
  241.  
  242.             You can apply separate gamma values to the red,
  243.             green, and blue channels of the image with a gamma
  244.             value list delineated with commas (i.e. 1.7,2.3,1.2).
  245.  
  246.        -geometry <width>{%}x<height>{%}{!}
  247.             preferred width and height of the image.  See X(1)
  248.             for details about the geometry specification.
  249.  
  250.             By default, the width and height are maximum values.
  251.             That is, the image is expanded or contracted to fit
  252.             the width and height value while maintaining the
  253.             aspect ratio of the image.  Append an exclamation
  254.             point to the geometry to force the image size to
  255.             exactly the size you specify.  For example, if you
  256.             specify 640x480! the image width is set to 640 pixels
  257.             and height to 480.  If only one factor is specified,
  258.             both the width and height assume the value.
  259.  
  260.             To specify a percentage width or height instead,
  261.             append %.  The image size is multiplied by the width
  262.             and height percentages to obtain the final image
  263.             dimensions.  To increase the size of an image, use a
  264.             value greater than 100 (e.g. 125%).  To decrease an
  265.             image's size, use a percentage less than 100.
  266.  
  267.        -interlace type
  268.             the type of interlacing scheme: NONE, LINE, or PLANE.
  269.  
  270.             This option is used to specify the type of
  271.             interlacing scheme for raw image formats such as RGB
  272.             or YUV.  NONE means do not interlace
  273.             (RGBRGBRGBRGBRGBRGB...), LINE uses scanline
  274.             interlacing (RRR...GGG...BBB...RRR...GGG...BBB...),
  275.             and PLANE uses plane interlacing
  276.             (RRRRRR...GGGGGG...BBBBBB...).  -label name assign a
  277.             label to an image.
  278.  
  279.             Use this option to assign a specific label to the
  280.             image.  Optionally you can include the image
  281.             filename, type, width, height, or scene number in the
  282.  
  283. ImageMagick                 1 May 1994                          5
  284.  
  285.             label by embedding special format characters.   Embed
  286.             %f for filename, %m for magick, %w for width, %h for
  287.             height, or %s for scene number.  For example,
  288.                  -label "%m:%f %wx%h"
  289.             produces an image label of MIFF:bird.miff 512x480 for
  290.             an image titled bird.miff and whose width is 512 and
  291.             height is 480.
  292.  
  293.             If the first character of string is @, the image
  294.             label is read from a file titled by the remaining
  295.             characters in the string.
  296.  
  297.             When converting to Postscript, use this option to
  298.             specify a header string to print above the image.
  299.  
  300.        -map filename
  301.             choose a particular set of colors from this image.
  302.  
  303.             By default, color reduction chooses an optimal set of
  304.             colors that best represent the original image.
  305.             Alternatively, you can choose a particular set of
  306.             colors with this option.  This is useful when you
  307.             want to create a sequence of images with one
  308.             particular set of colors for each image.
  309.  
  310.        -modulate value
  311.             vary the brightness, saturation, and hue of an image.
  312.  
  313.             Specify the percent change in brightness, the color
  314.             saturation, and the hue separated by commas.  For
  315.             example, to increase the color brightness by 20% and
  316.             decrease the color saturation by 10% and leave the
  317.             hue unchanged, use: -modulate 20,-10.
  318.  
  319.        -monochrome
  320.             transform the image to black and white.
  321.  
  322.        -negate
  323.             apply color inversion to image.
  324.  
  325.             The red, green, and blue intensities of an image are
  326.             negated.
  327.  
  328.        -noise
  329.             reduce the noise in an image with a noise peak
  330.             elimination filter.
  331.  
  332.             The principal function of noise peak elimination
  333.             filter is to smooth the objects within an image
  334.             without losing edge information and without creating
  335.             undesired structures.  The central idea of the
  336.             algorithm is to replace a pixel with its next
  337.             neighbor in value within a 3 x 3 window, if this
  338.             pixel has been found to be noise.  A pixel is defined
  339.  
  340. ImageMagick                 1 May 1994                          6
  341.  
  342.             as noise if and only if this pixel is a maximum or
  343.             minimum within the 3 x 3 window.
  344.  
  345.        -normalize
  346.             transform image to span the full range of color
  347.             values.
  348.  
  349.             This is a contrast enhancement technique.
  350.  
  351.        -opague color
  352.             change this color to the pen color within the image.
  353.             See -pen for more details.
  354.  
  355.        -page <width>x<height>{+-}<x offset>{+-}<y offset>
  356.             preferred size and location of the Postscript page.
  357.  
  358.             Use this option to specify the dimensions of the
  359.             Postscript page in pixels per inch or a TEXT page in
  360.             pixels.  The default for a Postscript page is to
  361.             center the image on a letter page 612 by 792 pixels.
  362.             The margins are 1/2" (i.e.  612x792+36+36).  Other
  363.             common sizes are:
  364.  
  365.                 Letter      612x 792
  366.                 Tabloid     792x1224
  367.                 Ledger     1224x 792
  368.                 Legal       612x1008
  369.                 Statement   396x 612
  370.                 Executive   540x 720
  371.                 A3          842x1190
  372.                 A4          595x 842
  373.                 A5          420x 595
  374.                 B4          729x1032
  375.                 B5          516x 729
  376.                 Folio       612x 936
  377.                 Quarto      610x 780
  378.                 10x14       720x1008
  379.  
  380.             For convenience you can specify the page size by
  381.             media (e.g.  A4, Ledger, etc.).
  382.  
  383.             The page geometry is relative to the vertical and
  384.             horizontal density of the Postscript page.  See
  385.             -density for details.
  386.  
  387.             The default page dimensions for a TEXT image is
  388.             612x792.
  389.  
  390.        -paint
  391.             paint the image.
  392.  
  393.        -pen color
  394.             set the color of the font or opague color.  See
  395.             -annotate or -opague for further details.
  396.  
  397. ImageMagick                 1 May 1994                          7
  398.  
  399.             See X(1) for details about the color specification.
  400.  
  401.        -quality value
  402.             JPEG quality setting.
  403.  
  404.             Quality is 0 (worst) to 100 (best). The default is
  405.             75.
  406.  
  407.        -roll {+-}<x offset>{+-}<y offset>
  408.             roll an image vertically or horizontally.  See X(1)
  409.             for details about the geometry specification.
  410.  
  411.             A negative x offset rolls the image left-to-right.  A
  412.             negative y offset rolls the image top-to-bottom.
  413.  
  414.        -rotate degrees
  415.             apply Paeth image rotation to the image.
  416.  
  417.             Empty triangles left over from rotating the image are
  418.             filled with the color defined as bordercolor (class
  419.             borderColor).  See X(1) for details.
  420.  
  421.        -scene value
  422.             image scene number.
  423.  
  424.        -sharpen weight
  425.             sharpen an image.  Specify factor as the percent
  426.             enhancement (0.0 - 99.9%).
  427.  
  428.        -shear <x degrees>x<y degrees>
  429.             shear the image along the X or Y axis by a positive
  430.             or negative shear angle.
  431.  
  432.             Shearing slides one edge of an image along the X or Y
  433.             axis, creating a parallelogram.  An X direction shear
  434.             slides an edge along the X axis, while a Y direction
  435.             shear slides an edge along the Y axis.  The amount of
  436.             the shear is controlled by a shear angle.  For X
  437.             direction shears, x degrees> is measured relative to
  438.             the Y axis, and similarly, for Y direction shears y
  439.             degrees is measured relative to the X axis.
  440.  
  441.             Empty triangles left over from shearing the image are
  442.             filled with the color defined as bordercolor (class
  443.             borderColor).  See X(1) for details.
  444.  
  445.        -size <width>{%}x<height>{%}{+colors}{!}
  446.             width and height of the image.
  447.  
  448.             Use this option to specify the width and height of
  449.             raw images whose dimensions are unknown such as GRAY,
  450.             RGB, or CMYK.  In addition to width and height, use
  451.             -size to tell the number of colors in a MAP image
  452.             file, (e.g. -size 640x512+256).
  453.  
  454. ImageMagick                 1 May 1994                          8
  455.  
  456.             For Photo CD images, choose from these sizes:
  457.  
  458.             192x128
  459.             384x256
  460.             768x512
  461.            1536x1024
  462.            3072x2048
  463.  
  464.        Finally, use this option to choose a particular resolution
  465.        layer of a JBIG image (e.g. -size 1024x768).
  466.  
  467.        -transparency color
  468.             make this color transparent within the image.
  469.  
  470.        -treedepth value
  471.             Normally, this integer value is zero or one.  A zero
  472.             or one tells mogrify to choose a optimal tree depth
  473.             for the color reduction algorithm.
  474.  
  475.             An optimal depth generally allows the best
  476.             representation of the source image with the fastest
  477.             computational speed and the least amount of memory.
  478.             However, the default depth is inappropriate for some
  479.             images.  To assure the best representation, try
  480.             values between 2 and 8 for this parameter.  Refer to
  481.             quantize(9) for more details.
  482.  
  483.             The -colors or -monochrome option is required for
  484.             this option to take effect.
  485.  
  486.        -undercolor <undercolor factor>x<black-generation factor>
  487.             control undercolor removal and black generation on
  488.             CMYK images.
  489.  
  490.             This option enables you to perform undercolor removal
  491.             and black generation on CMYK images-- images to be
  492.             printed on a four-color printing system. You can
  493.             control how much cyan, magenta, and yellow to remove
  494.             from your image and how much black to add to it.  The
  495.             standard undercolor removal is 1.0x1.0.  You'll
  496.             frequently get better results, though, if the
  497.             percentage of black you add to your image is slightly
  498.             higher than the percentage of C, M, and Y you remove
  499.             from it.  For example you might try 0.5x0.7.
  500.  
  501.        -verbose
  502.             print detailed information about the image.
  503.  
  504.             This information is printed: image scene number;
  505.             image name;  image size; the image class (DirectClass
  506.             or PseudoClass); the total number of unique colors
  507.             (if known);  and the number of seconds to read and
  508.             transform the image.  Refer to miff(5) for a
  509.             description of the image class.
  510.  
  511. ImageMagick                 1 May 1994                          9
  512.  
  513.             If -colors is also specified, the total unique colors
  514.             in the image and color reduction error values are
  515.             printed.  Refer to quantize(9) for a description of
  516.             these values.
  517.  
  518.        Options are processed in command line order.  Any option
  519.        you specify on the command line remains in effect until it
  520.        is explicitly changed by specifying the option again with
  521.        a different effect.  For example, to mogrify two images,
  522.        the first with 32 colors and the second with only 16
  523.        colors, use:
  524.  
  525.             mogrify -colors 32 cockatoo.miff -colors 16
  526.        macaw.miff
  527.  
  528.        Change - to + in any option above to reverse its effect.
  529.        For example, specify +compress to store the binary image
  530.        in an uncompressed format.
  531.  
  532.        By default, the image format is determined by its magic
  533.        number. To specify a particular image format, precede the
  534.        filename with an image format name and a colon (i.e.
  535.        ps:image) or specify the image type as the filename suffix
  536.        (i.e. image.ps).  See convert(1) for a list of valid image
  537.        formats.
  538.  
  539.        Specify file as - for standard input and output.  If file
  540.        has the extension .Z or .gz, the file is uncompressed with
  541.        uncompress or gunzip respectively and subsequently
  542.        compressed using with compress or gzip.  Finally, precede
  543.        the image file name with | to pipe to or from a system
  544.        command.
  545.  
  546.        Use an optional index enclosed in brackets after a file
  547.        name to specify a desired subimage of a multi-resolution
  548.        image format like Photo CD (e.g. img0001.pcd[4]).
  549.  
  550. SEE ALSO
  551.        display(1), animate(1), import(1), montage(1), convert(1),
  552.        segment(1), combine(1), xtp(1)
  553.  
  554. COPYRIGHT
  555.        Copyright 1995 E. I. du Pont de Nemours and Company
  556.  
  557.        Permission to use, copy, modify, distribute, and sell this
  558.        software and its documentation for any purpose is hereby
  559.        granted without fee, provided that the above copyright
  560.        notice appear in all copies and that both that copyright
  561.        notice and this permission notice appear in supporting
  562.        documentation, and that the name of E. I. du Pont de
  563.        Nemours and Company not be used in advertising or
  564.        publicity pertaining to distribution of the software
  565.        without specific, written prior permission.  E. I. du Pont
  566.        de Nemours and Company makes no representations about the
  567.  
  568. ImageMagick                 1 May 1994                         10
  569.  
  570.        suitability of this software for any purpose.  It is
  571.        provided "as is" without express or implied warranty.
  572.  
  573.        E. I. du Pont de Nemours and Company disclaims all
  574.        warranties with regard to this software, including all
  575.        implied warranties of merchantability and fitness, in no
  576.        event shall E. I. du Pont de Nemours and Company be liable
  577.        for any special, indirect or consequential damages or any
  578.        damages whatsoever resulting from loss of use, data or
  579.        profits, whether in an action of contract, negligence or
  580.        other tortuous action, arising out of or in connection
  581.        with the use or performance of this software.
  582.  
  583. ACKNOWLEDGEMENTS
  584.        Michael Halle, Spatial Imaging Group at MIT, for the
  585.        initial implementation of Alan Paeth's image rotation
  586.        algorithm.
  587.  
  588.        David Pensak, E. I. du Pont de Nemours and Company, for
  589.        providing a computing environment that made this program
  590.        possible.
  591.  
  592.        Paul Raveling, USC Information Sciences Institute, for the
  593.        original idea of using space subdivision for the color
  594.        reduction algorithm.
  595.  
  596. AUTHORS
  597.        John Cristy, E.I. du Pont de Nemours and Company
  598.        Incorporated
  599.  
  600. ImageMagick                 1 May 1994                         11
  601.  
  602.